home *** CD-ROM | disk | FTP | other *** search
/ Over 1,000 Windows 95 Programs / Over 1000 Windows 95 Programs (Microforum) (Disc 1).iso / 1271 / wsc4vb_u.doc < prev    next >
Text File  |  1997-03-19  |  45KB  |  1,203 lines
  1.  
  2.  
  3.  
  4.                      Windows Standard Communications
  5.  
  6.                          Library for Visual Basic
  7.  
  8.                                  (WSC4VB)
  9.  
  10.  
  11.                               USERS MANUAL
  12.  
  13.  
  14.  
  15.                                Version 2.0
  16.  
  17.                              March 15, 1997
  18.  
  19.  
  20.  
  21.  
  22.                      This software is provided as-is.
  23.               There are no warranties, expressed or implied.
  24.  
  25.  
  26.  
  27.  
  28.                          Copyright (C) 1996-1997
  29.                            All rights reserved
  30.  
  31.  
  32.  
  33.                         MarshallSoft Computing, Inc.
  34.                            Post Office Box 4543
  35.                            Huntsville AL 35815
  36.  
  37.                            Voice : 205-881-4630
  38.                              FAX : 205|880|0925
  39.                              BBS : 205-880-9748
  40.                            email : info@marshallsoft.com
  41.                              web : www.marshallsoft.com
  42.  
  43.                                _______
  44.                           ____|__     |                (R)
  45.                        --+       |    +-------------------
  46.                          |   ____|__  |  Association of
  47.                          |  |       |_|  Shareware
  48.                          |__|   o   |    Professionals
  49.                        --+--+   |   +---------------------
  50.                             |___|___|    MEMBER
  51.  
  52.  
  53.       MARSHALLSOFT is a trademark of MarshallSoft Computing, Inc.
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.      WSC4VB Users Manual                                       Page 1
  61.  
  62.                             C O N T E N T S
  63.  
  64.  
  65.  
  66.  
  67.  
  68.       Chapter                                                   Page
  69.  
  70.        1.0 Introduction................................................3
  71.            1.1 User Support............................................4
  72.            1.2 ASP Ombudsman...........................................4
  73.            1.3 Determining UART Address & IRQ Settings.................5
  74.            1.4 Installation............................................6
  75.        2.0 Library Overview............................................7
  76.            2.1 Dynamic Link Libraries..................................7
  77.            2.2 Using the Library.......................................7
  78.            2.3 Compiling Programs......................................7
  79.            2.4 Source Code.............................................7
  80.        3.0 Talking to Your Modem.......................................8
  81.            3.1 Modem Standards.........................................8
  82.            3.2 Flow Control...........................................10
  83.            3.3 Modem Initialization...................................10
  84.        4.0 Modem I/O..................................................11
  85.            4.1 MIO Introduction.......................................11
  86.            4.2 MIO Function Summary...................................11
  87.        5.0 XMODEM & YMODEM ...........................................12
  88.            5.1 XYDRIVER Introduction..................................12
  89.            5.2 XYDRIVER Function Summary..............................12
  90.        6.0 Problems...................................................13
  91.        7.0 Serial Communications......................................14
  92.            7.1 Communications Basics..................................14
  93.            7.2 RS232 Signals..........................................15
  94.        8.0 Example Programs...........................................16
  95.            8.1 EASY...................................................16
  96.            8.2 SELFTEST...............................................16
  97.            8.3 MODEM..................................................16
  98.            8.4 TERM...................................................16
  99.       9.0 Legal Issues................................................19
  100.           9.1 Registration............................................18
  101.           9.2 License.................................................18
  102.           9.3 Warranty................................................18
  103.       10.0 Summary....................................................19
  104.           10.1 Revision History.......................................19
  105.           10.2 WSC Function Summary...................................19
  106.           10.3 Further Reading........................................20
  107.       11.0 Other MarshallSoft Computing Products......................20
  108.           11.1 Personal Communications Library for VB / Windows.......20
  109.           11.2 Personal Communications Library for VB / DOS...........20
  110.           11.3 Libraries for Other Languages..........................20
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.      WSC4VB Users Manual                                       Page 2
  121.  
  122.       1.0 Introduction
  123.  
  124.       The Windows Standard Communications Library for Visual Basic
  125.       (WSC4VB) is an asynchronous communications dynamic link library (DLL)
  126.       which uses the standard Windows serial communications API. Since it
  127.       uses the Windows API, programs using the WSC library are fully
  128.       compatible with other Window applications which also use the Windows
  129.       serial communications API. Both Win16 and Win32 versions are
  130.       included.
  131.  
  132.       Using WSC is very straight-forward. For example, to write 'HELLO' to
  133.       the serial port COM1:
  134.  
  135.            Code = SioReset(COM1,128,128)     ' open COM1
  136.            Code = SioPuts(COM1,"HELLO",5)    ' write 'HELLO' to COM1
  137.            Code = SioDone(COM1)              ' close COM1
  138.  
  139.       Five Visual Basic example programs with full source code are included.
  140.       Refer to chapter 8 for more details on each of the example programs.
  141.  
  142.                EASY : A simple terminal emulator.
  143.  
  144.            SELFTEST : Performs COM port functionality testing.
  145.  
  146.               MODEM : Same as EASY but controls flow control, modem
  147.                       lines, etc.
  148.  
  149.                TERM : Terminal emulator with XMODEM & YMODEM.
  150.  
  151.       WSC4VB contains over 30 functions. All functions return a negative
  152.       number if an error condition is detected.  For more details, consult
  153.       the WSC4VB Reference Manual
  154.  
  155.       WSC4VB uses the same function names and arguments as WSC4C (C/C++)
  156.       and WSC4D (Delphi).
  157.  
  158.       Our goal is to provide a robust serial communications library that
  159.       that you and your customers can depend upon. Contact us if you have
  160.       any questions.
  161.  
  162.       The shareware and registered versions are identical except for two
  163.       differences: (1) the shareware version displays the 'shareware'
  164.       screen, and (2) the shareware version will 'time out' after 20
  165.       minutes, limiting execution to a maximum of ten minutes each time a
  166.       program is run. Of course, the registered version does not display
  167.       the shareware screen nor time out after twenty minutes.
  168.  
  169.       We apologize for the inconvenience of the shareware screen and
  170.       time-outs, but it is necessary to encourage registration by some who
  171.       would use the library (sometimes for years) without registering.
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.      WSC4VB Users Manual                                       Page 3
  181.  
  182.       1.1 User Support
  183.  
  184.       We want you to be successful in developing your applications using
  185.       WSC4VB! We depend upon our customers to let us know what they need in
  186.       a communications library.  This means we are committed to providing
  187.       the best communications library that we can. If you have any
  188.       suggestions or comments, please let us know.
  189.  
  190.       If you are having a problem using WSC4VB, call us at 205-881-4630
  191.       between 1:30PM and 9:30PM CST Monday through Friday. You can also
  192.       call at other times and leave a message, and call back later for a
  193.       reply.
  194.  
  195.       However, we can only answer questions with respect to using the
  196.       WSC4VB library.  We cannot help you program your application.
  197.  
  198.       If you are on the Internet, email us at info@marshallsoft.com.  You
  199.       can also get the latest versions of our products from our anonomous
  200.       ftp site:
  201.  
  202.             ftp://ftp.marshallsoft.com/marshallsoft
  203.  
  204.       You may also call our User Support BBS (2400 to 14400 baud, no
  205.       parity, 8 data bits, 1 stop bit) at 205-880-9748 and leave a message
  206.       (address it to the SYSOP).  We will reply within 24 hours.
  207.  
  208.       The BBS is available 24 hours per day except at 2 PM Sundays for
  209.       maintenanace. All files are in standard ZIP format. The BBS will
  210.       contain the latest shareware version of all MarshallSoft products as
  211.       well as related files such as:
  212.  
  213.            BUGS.ZIP:  Bug report.
  214.            NEWS.ZIP:  Latest news regarding our products.
  215.  
  216.       The MarshallSoft Computing, Inc. newsletter 'Comm Talk' is published
  217.       quarterly.  It discusses various communications problems and
  218.       solutions using WSC4VB as well as related information.
  219.  
  220.       The latest copy of our newsletter can be found on our User Support
  221.       BBS (in file area 'Newsletters'), our anonymous ftp site (directory
  222.       /marshallsoft) as well as our web site.
  223.  
  224.           http://www.marshallsoft.com
  225.  
  226.       1.2 ASP Ombudsman
  227.  
  228.       MarshallSoft Computing, Inc.  is a member of the Association of
  229.       Shareware Professionals (ASP).  ASP wants to make sure that the
  230.       shareware principle works for you.  If you are unable to resolve a
  231.       shareware-related problem with an ASP member by contacting the member
  232.       directly, ASP may be able to help.  The ASP Ombudsman can help you
  233.       resolve a dispute or problem with an ASP member, but does not provide
  234.       technical support for members' products. Please write to the ASP
  235.       Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax
  236.       616-788-2765, or send a CompuServe message via CompuServe Mail to ASP
  237.       Ombudsman 70007,3536.
  238.  
  239.  
  240.      WSC4VB Users Manual                                       Page 4
  241.  
  242.       1.3 Determining UART Address & IRQ Settings
  243.  
  244.       You will not normally need to know the port addresses or IRQ
  245.       assignments made by Windows. But this information is maintained by
  246.       Windows and is available if you need it.
  247.  
  248.       Both Windows 3.X and Windows 95 maintain a list of serial port
  249.       settings.  On Windows 3.X systems, choose the 'Ports' icon in the
  250.       'Control Panel' in the 'Main Group'.  Select 'Settings' and then
  251.       'Advanced' to view the COM port UART address and IRQ settings.
  252.  
  253.       In Windows 95, choose 'My Computer' icon ('or whatever your computer
  254.       icon is named), select the 'Control Panel' folder and then the
  255.       'System' icon.  Click on the 'Device Manager' tab.  Click 'Computer'
  256.       and then click 'Properties'. Click the 'View Resources' tab.  To view
  257.       reserved resources, click the resource type at the top of the dialog
  258.       box (i.e., 'Interrupt request (IRQ)' or 'Input/output (I/O)' ).
  259.  
  260.       The four standard COM ports which Windows typically controls are:
  261.  
  262.             Port  Address  IRQ
  263.             COM1   0x3F8    4
  264.             COM2   0x2F8    3
  265.             COM3   0x3E8    4
  266.             COM4   0x2E8    3
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.      WSC4VB Users Manual                                       Page 5
  301.  
  302.       1.4 Installation
  303.  
  304.       (1) Before installation of WSC4VB, your Visual Basic compiler should
  305.       already be installed on your system and tested. Note that Visual
  306.       Basic 4.0+ is required in order to create Win32 programs.
  307.  
  308.       Examine the file 'FILES.LST' for a list of the distribution files.
  309.  
  310.       (2) Make a backup copy of your distribution disk.  Put your original
  311.       distribution disk in a safe place.
  312.  
  313.       (3) Exit Windows into DOS, or start a DOS window:
  314.  
  315.       (4) Create your WSC project directory, copy the WSC archive, then
  316.       unzip the archive. For example:
  317.  
  318.                 MKDIR   WSC
  319.                 PKUNZIP WSC4VB20.ZIP WSC
  320.  
  321.       (5) Run the install program INSTALL.BAT which will copy the correct
  322.       files for your installation (Visual Basic 3.0 or Visual Basic 4.0+).
  323.  
  324.  
  325.       If you are using Visual Basic 3.0 (Win16), then type:
  326.  
  327.                 INSTALL 16
  328.  
  329.       If you are using Visual Basic 4.0 (Win32), then type:
  330.  
  331.                 INSTALL 32
  332.  
  333.       The install program creates WSC4VB.BAS from either WSC16.BAS or
  334.       WSC32.BAS, and copies the proper DLLs. This way, the source code for
  335.       the example programs is identical for both Visual Basic 3.0 (Win16)
  336.       and Visual Basic 4.0 (Win32).
  337.  
  338.       (6) Copy the library DLL files to your Visual Basic compiler's
  339.       directory, since that is where Visual Basic will look for them.
  340.  
  341.       For Win16, copy WSC16.DLL, MIO16.DLL, and XYDRIV32.DLL.
  342.  
  343.       For Win32, copy WSC32.DLL, MIO32.DLL, and XYDRIV32.DLL.
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.      WSC4VB Users Manual                                       Page 6
  361.  
  362.       2.0 Library Overview
  363.  
  364.       2.1 Dynamic Link Libraries
  365.  
  366.       WSC4VB includes both Win16 [WSC16] and a Win32 [WSC32] dynamic link
  367.       library (DLL). A DLL is characterized by the fact that it need not be
  368.       loaded until required by an application program and that only one
  369.       copy of the DLL is necessary regardless of the number of application
  370.       programs that use it. Contrast this to the traditional static library
  371.       which is bound to each and every application that uses it at link
  372.       time.
  373.  
  374.       Since WSC4VB is a DLL, only one copy of the WSC4VB code and data is
  375.       loaded into memory regardless of the number of applications programs
  376.       that use it. For example, more than one instance of the test program
  377.       EASY can be started.  All copies of EASY can run concurrently as
  378.       long as each uses a different COM port.
  379.  
  380.       2.2 Using the Library
  381.  
  382.       The WSC4VB has been tested on a Gateway 2000 25 MHZ 80386-DX, a
  383.       Gateway 2000 66MHZ 80486-DX2 (Windows 3.1), and a Mid-West Micro
  384.       150MHZ Pentium (Windows 95).
  385.  
  386.       Please examine the WSC4VB.BAS file. Note that COM1 is defined as port
  387.       zero, not port one.  The user must assume the responsibilty for
  388.       passing the correct information when calling WSC4VB functions.
  389.  
  390.       We recommend that you experiment with the four example programs.
  391.  
  392.       2.3 Compiling Programs
  393.  
  394.       Each of the example program should be compiled and run. In Visual Basic,
  395.       its easy!
  396.  
  397.       Before beginning, be sure to run INSTALL that will copy the proper
  398.       Win16 (or Win32) files.
  399.  
  400.       2.4 Source Code
  401.  
  402.       The source code for WSC.DLL, MIO.DLL, and XYDRIVER.DLL is written in
  403.       ANSI C, and is included in the registered archive.
  404.  
  405.       To compile these programs from source, the Microsoft C/C++ Windows
  406.       compiler is required.
  407.  
  408.       All source code for the example programs is included in both the
  409.       shareware and registered archive. All example programs compile under
  410.       both Visual Basic 3.0 (Win16) and Visual Basic 4.0 (Win32).
  411.  
  412.       The same set of DLLs is used for all WSC products: C/C++ (WSC4C),
  413.       Visual Basic (WSC4VB) and Visual Basic (WSC4VB).
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.      WSC4VB Users Manual                                       Page 7
  421.  
  422.       3.0 Talking to Your Modem
  423.  
  424.       A modem is used to extend the distance over which you may
  425.       communicate. Without a modem, your RS232 cable is limited to a
  426.       maximum of approximately 50 feet.  But with a modem, you can
  427.       communicate literally around the world.
  428.  
  429.       3.1 Modem Standards
  430.  
  431.       Two modems can communicate over a telephone line only if they are
  432.       both using the same signaling frequencies and modulation, which are
  433.       determined by the the modem standards used.  Modem standards can be
  434.       divided into three sets: (1) speed, (2) data compression used, and
  435.       (3) error control.
  436.  
  437.       The Bell standards (103 & 212A) are those of AT&T.  The CCITT (The
  438.       International Consultative Committee for Telephone and Telegraph)
  439.       standards are designated as 'V. '.
  440.  
  441.       Speed
  442.  
  443.            Bell 103  :   300 baud
  444.            Bell 212A :  1200 baud
  445.            V.21      :   300 baud
  446.            V.22bis   :  1200 & 2400 baud
  447.            V.32      :  4800 & 9600 baud
  448.            V.32bis   :  4800, 7200, 9600, 12000, and 14400 baud
  449.            V.34      :  to 28800 baud.
  450.  
  451.       Data Compression
  452.  
  453.            MNP 5     :  Microcom Networking Protocol (proprietary).
  454.            V.42bis   :  International data compression standard.
  455.  
  456.       Error Control
  457.  
  458.            MNP 2,3,4 :  Three level error correction (public domain).
  459.            V.42      :  International error correction standard.
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.      WSC4VB Users Manual                                       Page 8
  481.  
  482.       3.2 Flow Control
  483.  
  484.       With modems using data compression, the modem to modem connection
  485.       will run at various speeds depending on the quality of the line.
  486.       The computer to modem connection will be at a fixed baud rate.
  487.       Therefore, a protocol (flow control) is necessary to synchronize the
  488.       data flow between a modem and the computer to which it is connected.
  489.       Refer to your modem manual for information on flow control protocols
  490.       supported.
  491.  
  492.       Two flow control protocols are used by most all modems which require
  493.       flow control.  Software flow control is called 'XON/XOFF' (other
  494.       software flow control character pairs are defined but operate the
  495.       same as XON/XOFF) and hardware flow control is called 'RTS/CTS'. Most
  496.       modems which require flow control enable hardware flow control by
  497.       default.
  498.  
  499.       In XON/XOFF (software) flow control, the computer suspends
  500.       transmitting data if it receives a XOFF character (13 hex) from the
  501.       modem, and continues transmitting when it receives a XON character
  502.       (11 hex).  Similiarly, the computer can signal the modem not to send
  503.       any more data by transmitting a XOFF to it, and can tell the modem to
  504.       continue transmission be sending a XON.
  505.  
  506.       In RTS/CTS (hardware) flow control, the RTS line is used by the
  507.       computer to signal the modem , while the CTS line is used by the
  508.       modem to signal the computer.  The RTS line is set OFF by the
  509.       computer to tell the modem to suspend transmission, and set to ON to
  510.       tell the modem to continue transmission.  The CTS line is set to OFF
  511.       by the modem to tell the computer to stop transmitting, and set to ON
  512.       to tell the computer to continue transmitting.
  513.  
  514.       Given the choice, always choose hardware flow control over software
  515.       flow control so that all data transmission is transparent.  If
  516.       hardware flow control is not the default (which it almost always is),
  517.       you should modify your modem initialization string to turn hardware
  518.       flow control on.
  519.  
  520.       In order for flow control to work, both the computer and the modem
  521.       must set (hardware) flow control. Once SioFlow is called to set
  522.       hardware flow control, the modem should raise CTS immediately. If it
  523.       doesn't, then the modem has not enabled hardware flow control.
  524.  
  525.       WSC4VB supports both hardware and software flow control.  Refer to the
  526.       SioFlow function in the WSC4VB Reference Manual.
  527.  
  528.       NOTE: When hardware flow control is enabled (by calling SioFlow), no
  529.       serial I/O can occur until both DSR and CTS are set by the modem.
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.      WSC4VB Users Manual                                       Page 9
  541.  
  542.       3.3 Modem Initialization
  543.  
  544.       If your application uses a modem (as opposed to using a null modem
  545.       cable), then you should always send an initialization string to your
  546.       modem. Communication programs such as PROCOMM and TELIX always send
  547.       such a string automatically as soon as they start up.
  548.  
  549.       The particular initialization string depends on the make of your
  550.       modem.  For most modems, the following string (followed by a carriage
  551.       return) should work:
  552.  
  553.            AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
  554.  
  555.       Refer to your Modem User's Guide for a full discussion of these
  556.       commands.  A brief description is as follows:
  557.  
  558.            AT     Modem attention command.
  559.            E1     Modem will echo what you send to it.
  560.            S7=60  Wait 60 seconds for carrier and/or dial tone.
  561.            S11=60 Use 60 milliseconds for tone dialing duration & spacing.
  562.            V1     Display result code as words (not numbers).
  563.            X1     Use the extended result message (CONNECT XXXX) set.
  564.            Q0     Modem displays result codes.
  565.            S0=0   Do not answer RING.
  566.  
  567.       If your application will answer incoming calls, then set the S0
  568.       register to the ring on which to automatically answer.
  569.  
  570.       If you send the above codes by using SioPutc (as opposed to typing
  571.       them from the keyboard), then follow these guidelines:
  572.  
  573.       (1) Send an initial carriage return before the initialization string.
  574.  
  575.       (2) Pause at least 150 milliseconds after each character sent as
  576.       your modem needs the time to perform its own internal processing.
  577.       Pause a little longer if your modem is not accepting your
  578.       initialization string.
  579.  
  580.       (3) Pause one and a half seconds after sending any initialization
  581.       command such as ATZ or AT&F since your modem must do quite a bit of
  582.       processing.
  583.  
  584.       If you experience any problems in initializing your modem, you should
  585.       first reset it to factory settings by sending:
  586.  
  587.            AT&F
  588.  
  589.       Refer to the TERM program (function SendToModem is in the file MIO.C)
  590.       for an example of sending an initialization string to a modem.
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.      WSC4VB Users Manual                                       Page 10
  601.  
  602.       4.0 MODEM I/O (MIO)
  603.  
  604.       4.1 MIO Introduction
  605.  
  606.       The file MIO.BAS contains prototypes for using the Modem I/O DLL.
  607.       These functions ease communicating with modems using AT commands.
  608.       The TERM example has an example of using the MIO functions.
  609.  
  610.       The Windows 'operating system' is what is called 'cooperative
  611.       multitasking'. The executing Windows task must voluntarily 'give up'
  612.       control before another Windows task (or Windows itself) can execute.
  613.       The MIO functions are broken down into parts called states, and
  614.       control is returned to Windows between executing each state.
  615.  
  616.       For example:
  617.  
  618.       (1) Send the string to the MIO driver by executing:
  619.  
  620.       Code = mioSendTo(Port,100,"!ATDT1,205,880,9748")
  621.  
  622.       The '!' characters are converted to carriage returns.  The text
  623.       string is copied into the driver's data area.
  624.  
  625.       (2) Call mioDriver (typically based on a timer) until MIO_IDLE is
  626.       returned. Each time mioDriver is called, it will send another
  627.       character to the modem provided the required delay (since the
  628.       previous character was sent) has passed.  If the delay has not
  629.       passed, the driver simply returns MIO_RUNNING, but without actually
  630.       sending a character to the modem.  Once all characters have been
  631.       sent, mioDriver will return MIO_IDLE, indicating it is done and is
  632.       ready to accept another function.
  633.  
  634.       mioDriver will return MIO_RUNNING if it is still processing. Anything
  635.       else indicates that it is still processing and the returned value is
  636.       a character from the modem that can be displayed if wanted.
  637.  
  638.       (3) Once mioDriver returns MIO_IDLE, call mioResult to get the
  639.       result of the mioSendTo call.
  640.  
  641.       4.2 MIO Function Summary
  642.  
  643.        mioDriver : Drives the execution of mioSendTo, mioWaitFor, or
  644.                    mioQuiet once they have been started.
  645.         mioBreak : Forces the MIO driver to IDLE state.
  646.        mioSendTo : Sends a string (including control chars) to the modem.
  647.       mioWaitFor : Waits  for a particular string from the modem, passing
  648.                    all else through.
  649.         mioQuiet : Waits for continuous quiet of a specified duration.
  650.         mioBreak : Breaks further modem I/O activity.
  651.  
  652.       Refer to the WSC Reference Manual for more information.
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.      WSC4VB Users Manual                                       Page 11
  661.  
  662.       5.0 XMODEM & YMODEM
  663.  
  664.       5.1 XYDRIVER Introduction
  665.  
  666.       The XMODEM & YMODEM functions are implemented in XYDRIVER as a DLL
  667.       (Dynamic Link Library), and are state driven like the Modem I/O
  668.       functions described in the previous section. The TERM program
  669.       provides an example of using XYDRIVER.
  670.  
  671.       Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K,
  672.       and YMODEM. The basic procedure used to run XMODEM or YMODEM is as
  673.       follows:
  674.  
  675.       (1) Call xyAcquire immediately after calling SioReset.
  676.       (2) To receive a file, call xyStartRx, then call xyDriver
  677.           repeatedly until XY_IDLE is returned.
  678.       (3) To send a file, call xyStartTx, then call xyDriver repeatedly
  679.           until XY_IDLE is returned.
  680.       (4) Call xyRelease immediately before calling SioDone.
  681.  
  682.  
  683.  
  684.       5.2 XYDRIVER Function Summary
  685.  
  686.              xyAbort : Abort driver at any time.
  687.            xyAcquire : Acquire a port.
  688.              xyDebug : Set the debug level.
  689.             xyDriver : Executes the next state or states.
  690.         xyGetMessage : Get the next debug message.
  691.       xyGetParameter : Get a driver parameter.
  692.            xyRelease : Release a port.
  693.            xyStartRx : Start a receive.
  694.            xyStartTx : Start a transmit.
  695.  
  696.       Refer to the WSC Reference Manual for more information.
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.      WSC4VB Users Manual                                       Page 12
  721.  
  722.       6.0 Problems
  723.  
  724.       If you cannot get your application to run properly, first compile and
  725.       run the terminal emulator program EASY provided on your distribution
  726.       disk. Test EASY by connecting two computers with a null modem cable
  727.       or by commanding a Hayes AT command set compatible modem.
  728.  
  729.       Once EASY runs, compile and run the SELFTEST program.  This program
  730.       will test your serial ports' functionality.
  731.  
  732.       If your application does not run but EASY and SELFTEST run correctly,
  733.       then you have most likely made a programming mistake in your
  734.       application. MarshallSoft Computing cannot debug your application,
  735.       especially over the telephone!  However, consider each of the
  736.       following when searching for an error in your application.
  737.  
  738.       1.  Are your receive and transmit buffers large enough ? Use a buffer
  739.       size that is twice the size of the largest expected block.
  740.  
  741.       2.  Have you selected too high a baud rate? Windows can multitask
  742.       many tasks at once. You may have to lower your baud rate (or get
  743.       16550 UARTS).
  744.  
  745.       3.  Did SioReset return a zero value ?  If not, then you must call
  746.       SioReset again.
  747.  
  748.       4.  Did you send the proper initialization string to your modem ? Did
  749.       you set DTR and RTS? (you should).
  750.  
  751.       5. Are you trying to link a 32-bit DLL to a 16-bit program (or vice
  752.       versa)? Keep Win16 (Visual Basic 3.0) & Win32 (Visual Basic 4.0)
  753.       development separate.
  754.  
  755.       6. Are you connecting to your modem at a baud rate at least as high
  756.       as the fastest modem speed? For example, connect at 38400 for 28.8KB
  757.       modems.
  758.  
  759.       We recommend the following steps if you believe that you have
  760.       discovered a bug in the library: (1) Create the smallest, simpliest
  761.       test program possible that demonstrates the problem.  (2) Document
  762.       your exact machine configuration and what error the test program
  763.       demonstrates.  (3) Upload the example source to our user support BBS,
  764.       email it or mail us a disk.
  765.  
  766.       If the problem can be solved with an easy work-around, we will
  767.       publish the work-around.  If the problem requires a modification to
  768.       the library, we will make the change and make the modified library
  769.       available to our customers without charge.
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.      WSC4VB Users Manual                                       Page 13
  781.  
  782.       7.0 Serial Communications
  783.  
  784.       7.1 Communications Basics
  785.  
  786.       The heart of serial comm is the UART (Universal Asynchronous Receiver
  787.       Transmitter).  The IBM PC/XT/AT and compatibles use the 8250, 16450,
  788.       or the 16550 UART.  The purpose of the UART is:
  789.  
  790.       (1) To convert bytes from the CPU (Central Processing Unit), into a
  791.       serial format by adding the necessary start, stop, and parity bits to
  792.       each byte before transmission, and to then transmit each bit at the
  793.       correct baud rate.
  794.  
  795.       (2) To convert the incoming stream (at a specified baud rate) of
  796.       serial bits into bytes by removing the start, stop, and parity bits
  797.       before being made available to the CPU.
  798.  
  799.       The UART is part of the serial interface circuitry which allows the
  800.       CPU to send and receive signals over the RS232 lines. This can be
  801.       diagrammed as follows:
  802.  
  803.                             Serial Interface
  804.                          +-------------------+
  805.                          |                   |
  806.       +-----+  Data Bus  |     +------+      |    RS232 Signals
  807.       | CPU +------------+     | UART |      +----------------*
  808.       +-----+            |     +------+      |
  809.                          |                   |
  810.                          +-------------------+
  811.  
  812.       The 8250/16450/16550 UART is capable of operating in one of two
  813.       modes, 'polled' and 'interrupt driven'.  The serial communications
  814.       functions in the BIOS use the polled method.  In this approach, the
  815.       CPU is typically in a loop asking the UART over and over again if it
  816.       has a byte ready.  If its does, the polling code returns the byte.
  817.       But, if the next byte comes in before the polling code is executing
  818.       again, then that byte is lost.
  819.  
  820.       In the interrupt driven approach (used by Windows/WSC4VB), when a
  821.       byte is received by the UART, an 'Interrupt Service Routine' (ISR) is
  822.       executed immediately, suspending temporarily whatever else is
  823.       executing. The ISR then moves the byte to a buffer so that your
  824.       application program can later read it.
  825.  
  826.       Transmitted bytes are queued up awaiting transmission.  When a byte
  827.       is moved from the UART transmitter holding register to the UART
  828.       transmitter shift register, an interrupt is generated and the next
  829.       byte is taken from the library transmitter buffer by the ISR and
  830.       written to the UART holding register.
  831.  
  832.       Up to 16 bytes can be taken from the transmitter buffer while
  833.       processing one transmitter interrupt if an 16550 UART is used. The
  834.       16550 UART is strongly recommended for computers doing serial
  835.       communications under Windows.
  836.  
  837.  
  838.  
  839.  
  840.      WSC4VB Users Manual                                       Page 14
  841.  
  842.       7.2 RS-232 Signals
  843.  
  844.       RS-232 is the name of the serial data interface standard used to
  845.       connect computers to modems.  Most IBM compatible computers are built
  846.       with at least one serial port and use either DB9 (9 pin) or DB25 (25
  847.       pin) connectors.
  848.  
  849.       A summary of these pins and their function follows.  For more
  850.       detailed information, refer to one of the many books dealing with
  851.       RS-232 interfacing.
  852.  
  853.       Signal Ground Pin 7 (DB25), Pin 5 (DB9)
  854.  
  855.       The SG line is used as the common signal ground, and must always be
  856.       connected.
  857.  
  858.       Transmit Data Pin 2 (DB25), Pin 3 (DB9)
  859.  
  860.       The TX line is used to carry data from the computer to the modem.
  861.  
  862.       Receive Data Pin 3 (DB25), Pin 2 (DB9)
  863.  
  864.       The RX line is used to carry data from the modem to the computer.
  865.  
  866.       Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
  867.  
  868.       The DTR line is used by the computer to signal the modem that it is
  869.       ready. DTR should be set high when talking to a modem.
  870.  
  871.       Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
  872.  
  873.       The DSR line is used by the modem to signal the computer that it is
  874.       ready.
  875.  
  876.       Request to Send Pin 4 (DB25), Pin 7 (DB9)
  877.  
  878.       The RTS line is used to 'turn the line around' in half duplex
  879.       modems, and for hardware flow control in most modems that require
  880.       flow control.  RTS is controlled by the computer and read by the
  881.       serial device (modem).
  882.  
  883.       Clear to Send Pin 5 (DB25), Pin 8 (DB9)
  884.  
  885.       The CTS line is used to 'turn the line around' in half duplex
  886.       modems, and for hardware flow control in most modems that require
  887.       flow control.  CTS is controlled by the serial device (modem) and
  888.       read by the computer.
  889.  
  890.       Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
  891.  
  892.       The DCD line is used by the modem to signal the computer that a data
  893.       carrier signal is present.
  894.  
  895.       Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
  896.  
  897.       The RI line is asserted when a 'ring' occurs.
  898.  
  899.  
  900.      WSC4VB Users Manual                                       Page 15
  901.  
  902.       8.0 Example Programs
  903.  
  904.       Four example program are supplied.
  905.  
  906.       8.1 EASY
  907.  
  908.       EASY (EASY.MAK) is a very simple communications program using WSC4VB.
  909.       Everything that is typed on the keyboard is sent to the serial port,
  910.       and everthing incoming from the serial port is displayed on the
  911.       screen.
  912.  
  913.       The easiest way to test EASY is to connect to a modem.  Typing 'AT'
  914.       should result in an 'OK' being displayed.
  915.  
  916.       A null-modem cable can also be used to connect two computers together
  917.       with their serial ports. Run EASY on both machines. Whatever is typed
  918.       on one machine will be displayed on the other.
  919.  
  920.       8.2 SELFTEST
  921.  
  922.       SELFTEST (SELFTEST.MAK) performs a serial port I/O functionality
  923.       test. Either a pair of ports on the same computer (using a null modem
  924.       cable) or a single port (using a loopback adapter) can be tested.
  925.  
  926.       Refer to LOOPBACK.DOC for an explanation of how to make a loopback
  927.       adapter (without tools!).
  928.  
  929.       8.3 MODEM
  930.  
  931.       MODEM (MODEM.MAK) is similiar to EASY, but with enhanced capability.
  932.       It can set flow control (hardware, software, or none), DTR line (set
  933.       or clear), RTS line (set or clear), display the transmit & receive
  934.       queue sizes, detect a break signal, detect changes in DSR and CTS, as
  935.       well as check for various line errors (parity error, framing error,
  936.       data overrun, receive queue overflow, and transmit buffer full).
  937.  
  938.       8.4 TERM
  939.  
  940.       TERM (TERM.MAK) is a simple terminal emulator suitable for calling
  941.       up a BBS (such as ours) and downloading or uploading files using
  942.       XMODEM or YMODEM. The TERM program uses MIO.DLL for modem control
  943.       commands, and the XYDRIVER.DLL for XMODEM & YMODEM file transfer.
  944.  
  945.       Selecting 'Dial' from the menu bar will result in a pop-up dialog
  946.       requesting the phone number to dial. Once entered, the number is
  947.       dialed, and the program will wait for up to 60 seconds for the
  948.       'CONNECT' string from the modem.  This wait can be terminated at any
  949.       time by choosing 'BREAK' on the menu bar.
  950.  
  951.       Once logged on, files can be uploaded or downloaded by selecting
  952.       'Send' or 'Receive' from the menu bar. To abort a file transfer,
  953.       choose 'BREAK' from the menu bar then type a series of Ctrl-X (^X)
  954.       characters from the keyboard.
  955.  
  956.  
  957.  
  958.  
  959.  
  960.      WSC4VB Users Manual                                       Page 16
  961.  
  962.       9.0 Legal Issues
  963.  
  964.       9.1 Registration
  965.  
  966.       WSC4VB may be registered for $75 plus $5 S&H ($10 outside of North
  967.       America).
  968.  
  969.       To order, contact us as shown on the title page of this manual. All
  970.       prices are guaranteed for one year from the release date.
  971.  
  972.       Multiple copy discounts (3 or more) and site licenses are available.
  973.       Please call for details.
  974.  
  975.       We accept American Express, VISA, MasterCard, checks in US dollars
  976.       drawn on a US bank, International Postal Money Orders, purchase
  977.       orders (POs) from recognized US schools and companies listed in Dun &
  978.       Bradstreet, and COD (street address and phone number required) within
  979.       the USA (plus a $4.50 COD charge).
  980.  
  981.       For credit card orders, be sure to include the account number, the
  982.       expiration date, the exact name on the card, and the complete card
  983.       billing address (the address to which the credit card bill is
  984.       mailed).
  985.  
  986.       Print the file WSC4VB.INV if a 'Pro Forma' invoice is needed.
  987.  
  988.       If you wish to update from an older version of WSC4VB, send $25 plus
  989.       $5 S&H ($10 S&H outside of North America).
  990.  
  991.       The registered package includes:
  992.  
  993.            o  Win16 & Win32 WSC4VB Libraries w/o shareware screens.
  994.            o  Win16 & Win32 source code for WSC, MIO, and XYDRIVER.
  995.            o  Printed Users Manual & Reference Manual.
  996.            o  Telephone, BBS, and email support for one year.
  997.  
  998.       The registered user will receive the latest version of WSC4VB shipped
  999.       by US second day priority mail (packet airmail overseas).  A 3.5'
  1000.       HD diskette is provided.
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.      WSC4VB Users Manual                                       Page 17
  1021.  
  1022.       9.2 License
  1023.  
  1024.       MarshallSoft Computing, Inc. grants the registered user of WSC4VB the
  1025.       right to use one copy of the WSC4VB library (in object form) on a
  1026.       single computer in the development of any software product (other
  1027.       more than one computer at the same time.  The source code for the
  1028.       library (WSC16.C, WSC32.C, MIO.C, and XYDRIVER.C) is copyrighted by
  1029.       MarshallSoft Computing and may not be released in whole or in part.
  1030.       Products developed using WSC4VB may be distributed without royalty.
  1031.  
  1032.       9.3 Warranty
  1033.  
  1034.       MARSHALLSOFT COMPUTING, INC.  DISCLAIMS ALL WARRANTIES RELATING
  1035.       TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
  1036.       LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  1037.       A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
  1038.       SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR
  1039.       ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
  1040.       DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
  1041.       CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
  1042.       INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
  1043.       HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
  1044.       EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
  1045.       DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
  1046.       SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
  1047.       SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  1048.       SOFTWARE.
  1049.  
  1050.       Some states do not allow the exclusion of the limit of liability for
  1051.       consequential or incidental damages, so the above limitation may not
  1052.       apply to you.
  1053.  
  1054.       This agreement shall be governed by the laws of the State of Alabama
  1055.       and shall inure to the benefit of MarshallSoft Computing, Inc. and
  1056.       any successors, administrators, heirs and assigns.  Any action or
  1057.       proceeding brought by either party against the other arising out of
  1058.       or related to this agreement shall be brought only in a STATE or
  1059.       FEDERAL COURT of competent jurisdiction located in Madison County,
  1060.       Alabama. The parties hereby consent to in personam jurisdiction of
  1061.       said courts.
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.      WSC4VB Users Manual                                       Page 18
  1081.  
  1082.       10.0 Summary
  1083.  
  1084.       10.1 Revision History
  1085.  
  1086.       Version 1.0: 25 August, 1996.
  1087.  
  1088.           o  Original release.
  1089.  
  1090.       Version 2.0: 15 March, 1997.
  1091.  
  1092.           o  Includes Win16 and Win32 libraries.
  1093.           o  Added XMODEM & YMODEM DLL (XYDRIVER.DLL).
  1094.           o  Added TERM example program.
  1095.  
  1096.       10.2 WSC Function Summary
  1097.  
  1098.       Refer to the WSC4VB Reference Manual (WSC4VB_R.DOC) for detailed
  1099.       information on the communications and support functions.  A one line
  1100.       summary of each function follows:
  1101.  
  1102.       +-------------+-----------------------------------------------------+
  1103.       |  SioBaud    |  Sets the baud rate of the selected port.           |
  1104.       |  SioBrkSig  |  Asserts, cancels, or detects BREAK signal.         |
  1105.       |  SioCTS     |  Reads the Clear to Send (CTS) modem status bit.    |
  1106.       |  SioDCD     |  Reads the Data Carrier Detect (DCD) modem status.  |
  1107.       |  SioDone    |  Terminates further serial processing.              |
  1108.       |  SioDSR     |  Reads the Data Set Ready (DSR) modem status bit.   |
  1109.       |  SioDTR     |  Set, clear, or read the Data Terminal Ready (DTR). |
  1110.       |  SioFlow    |  Enables / disables hardware flow control.          |
  1111.       |  SioGetc    |  Reads the next character from the serial line.     |
  1112.       |  SioGets    |  Receives a string of characters.                   |
  1113.       |  SioInfo    |  Returns information such as library version.       |
  1114.       |  SioParms   |  Sets parity, stop bits, and word length.           |
  1115.       |  SioPutc    |  Transmit a character over a serial line.           |
  1116.       |  SioPuts    |  TRansmits a string of characters.                  |
  1117.       |  SioReset   |  Initialize a serial port for processing.           |
  1118.       |  SioRI      |  Reads the Ring Indicator (RI) modem status bit.    |
  1119.       |  SioRTS     |  Sets, clears, or reads the Request to Send (RTS).  |
  1120.       |  SioRxClea  |  Clears the receive buffer.                         |
  1121.       |  SioRxQue   |  Returns the number of characters in the RX queue.  |
  1122.       |  SioStatus  |  Returns the serial port line status.               |
  1123.       |  SioTxClea  |  Clears the transmit buffer.                        |
  1124.       |  SioTxQue   |  Returns the number of characters in the TX queue.  |
  1125.       |  SioUnGetc  |  'Un-gets' (puts back) a specified character.       |
  1126.       +-------------+-----+-----------------------------------------------+
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.      WSC4VB Users Manual                                       Page 19
  1141.  
  1142.       10.3 Further Reading
  1143.  
  1144.  
  1145.       The best way to learn about serial communications is to read a good
  1146.       book on the subject. Several good texts are available.  Two that I
  1147.       like are:
  1148.  
  1149.       (1) C Programmers's Guide to Serial Communications by Joe Campbell
  1150.       (SAMS) (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  1151.  
  1152.       You may also want to get a copy of one of our communications products
  1153.       which talks to the hardware directly.  They include more hardware
  1154.       specific documentation.
  1155.  
  1156.       11.0 Other MarshallSoft Computing Products
  1157.  
  1158.       Several shareware products are available from MarshallSoft Computing.
  1159.  
  1160.       11.1 The Personal Communications Library for VB / Windows
  1161.  
  1162.       The Personal Communications Library for VB / Windows (PCLVBW) is a
  1163.       Windows based [Win16] asynchronous communications library designed
  1164.       for software developers programming in Visual Basic.  Unlike WSC4VB,
  1165.       PCLVBW interfaces to the serial port hardware directly.  PCLVBW also
  1166.       supports multiport boards such as those made by DigiBoard and BOCA.
  1167.  
  1168.       The Personal Communications Library for VB / Windows (PCLVBW) is
  1169.       available for $75 plus $5 S&H ($10 S&H overseas).
  1170.  
  1171.       11.2 The Personal Communications Library for VB / DOS
  1172.  
  1173.       PCL4VB is similiar to PCLVBW except that it is designed for DOS.
  1174.  
  1175.       11.3 Libraries for Other Languages
  1176.  
  1177.       We have communications libraries for C/C++, Turbo Pascal, Visual
  1178.       Basic, and PowerBASIC.
  1179.  
  1180.        PCL4C  : C/C++, DOS [include 16-bit & 32-bt protected mode].
  1181.        PCL4P  : Turbo Pascal, DOS [includes 16-bit protected mode].
  1182.        PCL4VB : Visual Basic, DOS.
  1183.        PCL4PB : Power Basic, DOS.
  1184.  
  1185.         PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly.
  1186.        PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly.
  1187.  
  1188.         WSC4C : C/C++, Win 3.1 & Win 95, Win NT. Uses Windows API.
  1189.        WSC4VB : Visual Basic, Win 3.1 & Win 95. Uses Windows API.
  1190.         WSC4D : Borland Delphi, Win 3.1 & Win 95. Uses Windows API.
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.      WSC4VB Users Manual                                       Page 20
  1201.  
  1202.  
  1203.